<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<!-- saved from url=(0014)about:internet -->
<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<title>
	Using StatNetDriver
</title>

<link rel="stylesheet" href="_CodeDoc.css" />

<style type="text/css">
.Reference
{
	color: #003399;
}
</style>

</head>

<body id="DocBrowserTopic">

<div class="TopicHeader">
	<div class="Supertitle_">
		HomeUX Driver Collection
	</div>
	Using StatNetDriver
</div>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<div class="Summary">

<p>This page documents how to use <b>StatNetDriver</b> (in StatNetDriver.dll), the
HomeUX-compatible driver that controls an Enerzone StatNet thermostat network.
<b>StatNetSimulator</b> (in StatNetSimulator.dll) is also documented here.</p>

<p>Page contents:</p>
<ul>
	<li><a href="#Overview">Hardware &amp; Driver Overview</a></li>
	<li><a href="#Config">Configuring StatNetDriver</a></li>
	<li><a href="#Use">Using StatNetDriver</a></li>
	<li><a href="#Sim">StatNetSimulator</a></li>
</ul>

</div>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<div class="SectionHeader">
	Hardware &amp; Driver Overview<a name="Overview"></a>
</div>
<div id="DocTopic">
<div class="Section">

	<p>An Enerzone StatNet thermostat network is a collection of thermostats connected to a
	central control unit, which in turn can be controlled via serial port.</p>

	<p>StatNetDriver allows a HomeUX installation to control a subset of the functionality of a
	StatNet thermostat network:</p>
	<ul>

		<li>Thermostats are assigned names.</li>

		<li>You can query thermostats for current actual temperature, heating set point, cooling
		set point, and mode.</li>

		<li>You can set the heating set point, cooling set point, and mode of each thermostat.</li>

	</ul>

</div>
</div>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<div class="SectionHeader">
	Configuring StatNetDriver<a name="Config"></a>
</div>
<div id="DocTopic">
<div class="Section">

	<p>StatNetDriver is configured in the HomeUX configuration file.  Here's the general
	structure (simplified):</p>

	<table class="Grid Code">
		<col class="Column1_" />
		<tr class="Header_">
			<td class="Header1_">XML</td>
		</tr>
		<tr>
			<td class="Content_ Indent_">
				&lt;configuration&gt;
					<div>&lt;HomeUXSettings&gt;
						<div><a href="#Device">&lt;Device Driver="StatNetDriver.dll"&gt;</a>
							<div><a href="#Thermostat">&lt;Thermostat/&gt;</a>*</div>
						</div>
						<div>&lt;/Device&gt;</div>
					</div>
					<div>&lt;/HomeUXSettings&gt;</div>
				&lt;/configuration&gt;
			</td>
		</tr>
	</table>

	<p>"<tt>*</tt>" means "zero or more allowed".  Children of <tt>&lt;Device
	Driver="StatNetDriver.dll"&gt;</tt> can appear in any order.</p>

	<p>Example:</p>

	<table class="Grid Code">
		<col class="Column1_" />
		<tr class="Header_">
			<td class="Header1_">XML</td>
		</tr>
		<tr>
			<td class="Content_">
	<pre>
&lt;configuration&gt;
  ...
  &lt;HomeUXSettings&gt;
    ...

    &lt;Device Name="StatNet" Driver="StatNetDriver.dll" Scale="Fahrenheit"
          sim:SerialPort="StatNetSimulator.dll;;Units=4;OutTemp=45;Test=0"
          real:SerialPort="COM16,9600,8,n,1"&gt;

      &lt;Thermostat Id="1" Name="Living Room" /&gt;
      &lt;Thermostat Id="2" Name="Master Bedroom" /&gt;
      &lt;Thermostat Id="3" Name="Game Room" /&gt;
      &lt;Thermostat Id="4" Name="Guest Area" /&gt;

    &lt;/Device&gt;

  ...
  &lt;/HomeUXSettings&gt;
&lt;/configuration&gt;
	</pre>
			</td>
		</tr>
	</table>

	<p>The following subsections describe the StatNetDriver configuration file XML elements.</p>

	<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
	<div class="SubsectionHeader Reference">
		&lt;Device Driver="StatNetDriver.dll"&gt;<a name="Device"></a>
	</div>
	<div class="Section">

		<p>(Required, used within <tt>&lt;HomeUXSettings&gt;</tt>.) Specifies an instance of
		StatNetDriver, which is used to control a StatNet thermostat network.</p>

		<div class="SubsectionHeader">Syntax</div>
		<table class="Grid Code">
			<col class="Column1_" />
			<tr class="Header_">
				<td class="Header1_">XML</td>
			</tr>
			<tr>
				<td class="Content_ Indent_">
					&lt;Device
						<div>Name="..."</div>
						<div>Scale="..."</div>
						<div>Driver="StatNetDriver.dll"</div>
						<div>SerialPort="..."&gt;</div>
						<div><a href="#Thermostat">&lt;Thermostat/&gt;</a>*</div>
					&lt;/Device&gt;
				</td>
			</tr>
		</table>

		<p>"<tt>*</tt>" means "zero or more allowed".</p>

		<div class="SubsectionHeader">Attributes</div>
		<div class="Subsection">

			<div class="Subsection">
			<p class="AttributeName">Name</p>
			<p class="AttributeDescription">(String, required.)
				The name you assign to the device.
			</p>
			</div>

			<div class="Subsection">
			<p class="AttributeName">Driver</p>
			<p class="AttributeDescription">(String, required.)
				Must be "<tt>StatNetDriver.dll</tt>".
			</p>
			</div>

			<div class="Subsection">
			<p class="AttributeName">Scale</p>
			<p class="AttributeDescription">(String, required.)
				Specifies the measurement units that the thermostat uses; must be either
				"<tt>Fahrenheit</tt>" or "<tt>Celcius</tt>".
			</p>
			</div>

			<div class="Subsection">
			<p class="AttributeName">SerialPort</p>
			<p class="AttributeDescription">(String, required.)
				A standard HomeUX serial port specification.  Identifies the serial port (real or
				virtual) that the hardware is connected to.  When connected to a real serial port,
				the parameters should be "<i>port-name</i>,9600,8,n,1" in
				order to correctly operate a StatNet thermostat network.
			</p>
			</div>

		</div>

	</div>

	<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
	<div class="SubsectionHeader Reference">
		&lt;Thermostat&gt;<a name="Thermostat"></a>
	</div>
	<div class="Section">

		<p>(Zero or more, used within <a href="#Device">&lt;Device Driver="StatNetDriver.dll"&gt;</a>.)
		Specifies one thermostat on the StatNet thermostat network.</p>

		<div class="SubsectionHeader">Syntax</div>
		<table class="Grid Code">
			<col class="Column1_" />
			<tr class="Header_">
				<td class="Header1_">XML</td>
			</tr>
			<tr>
				<td class="Content_ Indent_">
					&lt;Thermostat
						<div>Id="..."</div>
						<div>Name="..."</div>
					/&gt;
				</td>
			</tr>
		</table>

		<div class="SubsectionHeader">Attributes</div>
		<div class="Subsection">

			<div class="Subsection">
			<p class="AttributeName">Id</p>
			<p class="AttributeDescription">(Integer, required.)
				The thermostat number (1 or above).
			</p>
			</div>

			<div class="Subsection">
			<p class="AttributeName">Name</p>
			<p class="AttributeDescription">(String, required.)
				The name you assign to the thermostat.  This name appears within alert messages,
				and is used within the <a href="#Use">SyncPath schema</a>.
			</p>
			</div>

		</div>

	</div>

</div>
</div>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<div class="SectionHeader">
	Using StatNetDriver<a name="Use"></a>
</div>
<div id="DocTopic">
<div class="Section">

	<p>StatNetDriver implements the following SyncPath schema:</p>
	<ul>

		<li><b><tt><i>device-name</i>\Thermostats\<i>thermostat-name</i>\ActualTemperature</tt></b><br/>
			Gets the actual temperature of thermostat <i>thermostat-name</i> of device
			<i>device-name</i>, specified as a number in the units (Fahrenheit or Celsius) defined
			in the configuration file.</li>

		<li><b><tt><i>device-name</i>\Thermostats\<i>thermostat-name</i>\Mode</tt></b><br/>
			Gets or sets the mode of thermostat <i>thermostat-name</i> of device
			<i>device-name</i>; one of the following:
			<ul>
				<li><tt>Off</tt> = thermostat off</li>
				<li><tt>Auto</tt> = auto cooling/heating mode</li>
				<li><tt>Cool</tt> = cooling mode</li>
				<li><tt>Heat</tt> = heating mode</li>
				<li><tt>EmergencyHeat</tt> = emergency heat mode</li>
			</ul>
			</li>

		<li><b><tt><i>device-name</i>\Thermostats\<i>thermostat-name</i>\HeatingSetPoint</tt></b><br/>
			Gets the heating set point (i.e. the temperature below which heating starts, when it's
			enabled) of device <i>device-name</i>, specified as a number in the units (Fahrenheit
			or Celsius) defined in the configuration file.</li>

		<li><b><tt><i>device-name</i>\Thermostats\<i>thermostat-name</i>\CoolingSetPoint</tt></b><br/>
			Gets the cooling set point (i.e. the temperature above which cooling starts, when it's
			enabled) of device <i>device-name</i>, specified as a number in the units (Fahrenheit
			or Celsius) defined in the configuration file.</li>

		<li><b><tt><i>device-name</i>\Thermostats\<i>thermostat-name</i>\IsFanOn</tt></b><br/>
			Gets or sets the fan setting of thermostat <i>thermostat-name</i> of device
			<i>device-name</i>, (<tt>true</tt> or <tt>false</tt>).</li>

		<li><b><tt>Configuration\<i>device-name</i>\ThermostatNames\<i>thermostat-name</i></tt></b><br/>
			Gets the display label for thermostat <i>thermostat-name</i> of device <i>device-name</i>;
			currently the display label is the same as <i>thermostat-name</i>.  This can be used to
			enumerate thermostats.</li>

	</ul>

</div>
</div>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<div class="SectionHeader">
	StatNetSimulator<a name="Sim"></a>
</div>
<div id="DocTopic">
<div class="Section">

	<p><b>StatNetSimulator</b> is a HomeUX-compatible virtual serial port implementation that
	simulates a subset of the serial communication behavior of StatNet hardware.  StatNetSimulator
	performs no real-world actions&mdash;the simulation is purely for the purposes of testing a
	HomeUX installation without having to connect to real hardware.</p>

	<p>To use StatNetSimulator in HomeUX, set the SerialPort attribute of the
	<a href="#Device">&lt;Device Driver="StatNetDriver.dll"&gt;</a> configuration element to a
	string with the following format:</p>

	<code class="Indent">
          StatNetSimulator.dll;;Units=<i>unit-count</i>;OutTemp=<i>outdoor-temperature</i>;Test=<i>test-number</i>
	</code>

	<p>Parameters:</p>
	<ul>

		<li><p><i>unit-count</i> is the number of simulated thermostats on the StatNet network.
			The default is 1.</p></li>

		<li><p><i>outdoor-temperature</i> is the simulated outdoor temperature in Fahrenheit
			degrees.  This affects how the room temperature will change when the HVAC system is not
			running.  The default is 50.</p></li>

		<li><p><i>test-number</i> specifies test behavior.  This is for development use only; use 0
			to specify normal behavior.  The default is 0.</p></li>

	</ul>

	<p>You can test StatNetSimulator independently of HomeUX, using the VSerial console
	application:</p>

	<code class="Indent">
          VSerial.exe -cr -dll StatNetSimulator.dll;;Units=<i>unit-count</i>;OutTemp=<i>outdoor-temperature</i>;Test=<i>test-number</i>
	</code>

	<p>StatNetSimulator implements a limited simulation&mdash;only the following hardware commands
	are currently supported.  (See StatNet hardware documentation for information about hardware
	commands and notifications.)</p>
	<ul>

 		<li><p>"SN?": Lists all thermostats.  Syntax:</p>
			<ul class="Compact">
				<li><tt>SN?</tt></li>
			</ul>
			</li>

			<p>The output looks like this (example):</p>

			<p class="Indent">
			<tt>SN1</tt><br/>
			<tt>SN2</tt><br/>
			<tt>SN3</tt><br/>
			</p>

 		<li><p>"SN SCALE=": Sets the units (Fahrenheit or Celcius) to use for all thermostats.
			Syntax:</p>
			<ul class="Compact">
				<li><tt>SN SCALE=<i>units</i></tt></li>
			</ul>
			<p><i>units</i> is "F" for Fahrenheit or "C" for Celcius.</p>
			</li>

			<p>The output looks like this (example):</p>

			<p class="Indent">
			<tt>SN1 SCALE=F</tt><br/>
			<tt>SN2 SCALE=F</tt><br/>
			<tt>SN3 SCALE=F</tt><br/>
			</p>

 		<li><p>"SN C=": Enables reporting of "change of state" notifications for all thermostats.
			Syntax:</p>
			<ul class="Compact">
				<li><tt>SN C<i>notification-number</i>=ON</tt></li>
				<li><tt>SN C<i>notification-number</i>=OFF</tt></li>
			</ul>
			<p><i>notification-number</i> is one of the following:</p>
			<ul class="Compact">
				<li><tt>1</tt> = HVAC control circuits (relays)</li>
				<li><tt>2</tt> = Temperature</li>
				<li><tt>3</tt> = Outdoor temperature</li>
				<li><tt>4</tt> = Contact closures</li>
				<li><tt>5</tt> = Thermostat set points (user keypad entry)</li>
				<li><tt>6</tt> = User HOLD function</li>
				<li><tt>7</tt> = Thermostat mode (user keypad input)</li>
				<li><tt>8</tt> = Thermostat fan switch (user keypad input)</li>
			</ul>
			</li>

			<p>The output looks like this (example):</p>

			<p class="Indent">
			<tt>SN1 C1=ON</tt><br/>
			<tt>SN2 C1=ON</tt><br/>
			<tt>SN3 C1=ON</tt><br/>
			</p>

 		<li><p>"SN T?": Lists the current actual temperature at each thermostat.  Syntax:</p>
			<ul class="Compact">
				<li><tt>SN T?</tt></li>
			</ul>
			</li>

			<p>The output looks like this (example):</p>

			<p class="Indent">
			<tt>SN1 T=73F</tt><br/>
			<tt>SN2 T=72F</tt><br/>
			<tt>SN3 T=65F</tt><br/>
			</p>

 		<li><p>"SN M?": Lists the mode of each thermostat.  Syntax:</p>
			<ul class="Compact">
				<li><tt>SN M?</tt></li>
			</ul>
			</li>

			<p>The output looks like this (example):</p>

			<p class="Indent">
			<tt>SN1 M=AUTO</tt><br/>
			<tt>SN2 M=COOL</tt><br/>
			<tt>SN3 M=OFF</tt><br/>
			</p>

 		<li><p>"SN SH?": Lists the heating set point of each thermostat.  Syntax:</p>
			<ul class="Compact">
				<li><tt>SN SH?</tt></li>
			</ul>
			</li>

			<p>The output looks like this (example):</p>

			<p class="Indent">
			<tt>SN1 SH=72F</tt><br/>
			<tt>SN2 SH=74F</tt><br/>
			<tt>SN3 SH=66F</tt><br/>
			</p>

 		<li><p>"SN SC?": Lists the cooling set point of each thermostat.  Syntax:</p>
			<ul class="Compact">
				<li><tt>SN SC?</tt></li>
			</ul>
			</li>

			<p>The output looks like this (example):</p>

			<p class="Indent">
			<tt>SN1 SC=76F</tt><br/>
			<tt>SN2 SC=78F</tt><br/>
			<tt>SN3 SC=69F</tt><br/>
			</p>

 		<li><p>"SN HVAC?": Reports the HVAC relay states of all thermostats.  Syntax:</p>
			<ul class="Compact">
				<li><tt>SN HVAC?</tt></li>
			</ul>
			</li>

			<p>The output looks like this (example):</p>

			<p class="Indent">
			<tt>SN1 HVAC=G-Y1-W1-Y2-W2-B-O-</tt><br/>
			<tt>SN2 HVAC=G+Y1-W1-Y2-W2-B+O-</tt><br/>
			<tt>SN3 HVAC=G+Y1-W1-Y2-W2-B+O-</tt><br/>
			</p>

			<p>The format of the HVAC codes are the same as those of HVAC notifications, described
			<a href="#HvacNotifications">below</a>.</p>

 		<li><p>"SN M=": Sets the mode of a given thermostat.  Syntax:</p>
			<ul class="Compact">
				<li><tt>SN<i>thermostat-number</i> M=<i>mode</i></tt></li>
			</ul>
			<p><i>thermostat-number</i> is the thermostat number (e.g. 1); <i>mode</i> is one of
			the following:</p>
			<ul class="Compact">
				<li><tt>OFF</tt> = thermostat off</li>
				<li><tt>AUTO</tt> = auto cooling/heating mode</li>
				<li><tt>COOL</tt> = cooling mode</li>
				<li><tt>HEAT</tt> = heating mode</li>
				<li><tt>E</tt> = emergency heat mode</li>
			</ul>
			</li>

			<p>The output has the same format as for the "SN M?" command, except only output for
			the specified thermostat is listed.</p>

 		<li><p>"SN SH=": Sets the heating set point of a given thermostat.  Syntax:</p>
			<ul class="Compact">
				<li><tt>SN<i>thermostat-number</i> SH=<i>temp</i></tt></li>
			</ul>
			<p><i>thermostat-number</i> is the thermostat number (e.g. 1); <i>temp</i> the integer
			temperature value (in the units specified by the "SN SCALE=" command), e.g. "72".</p>
			</li>

			<p>The output has the same format as for the "SN SH?" command, except only output for
			the specified thermostat is listed.</p>

 		<li><p>"SN SC=": Sets the cooling set point of a given thermostat.  Syntax:</p>
			<ul class="Compact">
				<li><tt>SN<i>thermostat-number</i> SC=<i>temp</i></tt></li>
			</ul>
			<p><i>thermostat-number</i> is the thermostat number (e.g. 1); <i>temp</i> the integer
			temperature value (in the units specified by the "SN SCALE=" command), e.g. "78".</p>
			</li>

			<p>The output has the same format as for the "SN SC?" command, except only output for
			the specified thermostat is listed.</p>

	</ul>

	<p>If notifications are enabled (see the "SN C=" command), notifications may be sent which
	mirror the replies from the "SN T?" and "SN HVAC?" commands.  Examples of notifications that
	could be sent by the simulated hardware:</p>

	<ul>
		<li><tt>SN1 T=73F</tt></li>
		<li><tt>SN2 SH=70F</tt></li>
		<li><tt>SN2 SC=80F</tt></li>
		<li><tt>SN1 M=HEAT</tt></li>
		<li><tt>SN3 HVAC=G+Y1-W1-Y2-W2-B+O-</tt></li>
	</ul>

	<p><a name="HvacNotifications"></a>HVAC notifications reflect which relays are energized:</p>
	<ul>
		<li><tt>G</tt> = fan</li>
		<li><tt>W1, W2</tt> = first and second stage heating</li>
		<li><tt>Y1, Y2</tt> = first and second stage cooling</li>
		<li><tt>B</tt> = heat mode</li>
		<li><tt>O</tt> = cool mode</li>
	</ul>

	<p>(The letters indicate the relay terminal color coding.)</p>

	<p>So, for example, if W1 or W2 are "+", the thermostat is requesting that the HVAC system
	generate warm air.  If Y1 or Y2 are "+", the thermostat is requesting that the HVAC system
	generate cool air.</p>

	<p>Sometimes a notification may arrive in the middle of a reply to a command (though, in the
	current simulator implementation, this only happens if "Test=1" is specified).  For example,
	the following may be received in response to an "SN T?" command:</p>

	<p class="Indent">
	<tt>SN1 T=74F</tt><br/>
	<tt>SN2 T=73F</tt><br/>
	<tt>SN3 T=65F</tt><br/>
	<tt>SN4 HVAC=G+Y1-W1-Y2-W2-B+O-</tt><br/>
	<tt>SN4 T=70F</tt>
	</p>

	<p>Note the "HVAC" notification between the "SN3" and "SN4" lines of the reply.</p>

</div>
</div>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<div class="TopicFooter">
</div>

<div class="PageFooter">
<p>See <a href="http://www.HomeUX.org">http://www.HomeUX.org</a> for more information about HomeUX.</p>
</div>

</body>

</html>

